docs: add AGENTS.md - #3576
Conversation
Maka already reads AGENTS.md — buildWorkspaceInstructionsPromptFragment injects the nearest one into the system prompt — but the repository has never had its own, so an agent working here starts with no context beyond the source tree. The file points rather than restates. Setup, the package map, contribution policy and architecture all have owners already, so duplicating them would create a second source of truth that goes stale unnoticed. What it keeps is the short list of things that are currently written down nowhere: that every workspace tests against compiled dist/ rather than src/, that Biome formats the tree except apps/desktop and packages/ui because desktop's source-contract tests regex-match exact source shapes, that some files are generated, and the working method the project's review habits already imply. Kept under the 6000-character limit that workspace-instructions.ts enforces on this very file, so Maka does not truncate its own instructions. The ASF header alone accounts for 13% of that budget. CLAUDE.md is a symlink to AGENTS.md, matching apache/airflow and the pattern the Claude Code documentation recommends: each agent CLI reads exactly one filename — Claude Code reads CLAUDE.md, Codex reads AGENTS.md, Gemini CLI reads GEMINI.md — so one canonical file plus a link avoids two copies that drift. Generated-by: Claude Code Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds repository-level guidance for coding agents through AGENTS.md.
Changes:
- Documents testing, formatting, generated files, licensing, and workflow conventions.
- Links to existing setup, contribution, architecture, and tooling documentation.
- Includes notes to clarify the
CLAUDE.mdsymlink claim and@maka/evaltest command.
Suppressed comments (6)
AGENTS.md:33
buildWorkspaceInstructionsPromptFragmentdoes not search ancestor directories: it reads only the exact sessioncwd(plus~/.maka) and the three filenames there. Calling this the “nearest” file is misleading for a session started in a nested directory, where the repository-rootAGENTS.mdis not loaded; please document the actual scope.
Maka reads this file itself — `buildWorkspaceInstructionsPromptFragment` injects the nearest
`AGENTS.md`, `CLAUDE.md`, or `GEMINI.md` into the system prompt — so it is live product input, not
only documentation. It is also truncated past 6000 characters, which is the hard reason to keep it
short.
AGENTS.md:82
- Generated artifacts are not limited to
*.generated.ts: the repository also generates the theme artifacts, the surface/test inventories, andapps/desktop/bundled-tools.json. As written, an agent can miss those and hand-edit build outputs; describe the suffix as one naming convention and include the other generated classes.
- **Some files are generated.** They match `*.generated.ts`; regenerate rather than hand-edit.
AGENTS.md:85
- “Every source file” contradicts the header policy: it deliberately excludes generated files, third-party source, fixtures, templates, and other non-Maka files; for example,
packages/core/src/model-metadata.generated.tsis undersrc/but is excluded. Following this advice could add headers to byte-sensitive or regenerated files, so qualify the rule and link the exclusion policy.
- **Every source file needs the ASF license header.** `npm run check:asf-headers` audits the whole
checkout, so stray untracked files can fail it. `node scripts/asf-license-headers.mjs write` adds
missing headers.
AGENTS.md:33
- This file explicitly says it is injected into the system prompt, so adding it changes model prompt behavior for sessions in this repository even though no runtime source changed. That conflicts with the checklist's “Does this PR entail a change in behavior? No”; mark it Yes or clarify that the checkbox excludes prompt inputs.
Maka reads this file itself — `buildWorkspaceInstructionsPromptFragment` injects the nearest
`AGENTS.md`, `CLAUDE.md`, or `GEMINI.md` into the system prompt — so it is live product input, not
only documentation. It is also truncated past 6000 characters, which is the hard reason to keep it
short.
AGENTS.md:56
- The heading is broader than the documented test contract:
@maka/eval'stest:distalso runs severalpython3 harbor/test_*.pysuites directly from source. Scope this section to TypeScript/Node tests so contributors editing those Python tests are not given a false workflow.
## Tests run from `dist/`, not `src/`
AGENTS.md:52
- The opening paragraph says this file avoids restating documentation owned elsewhere, but this section repeats the Runtime Host and Runtime Event Log invariants already stated in
ARCHITECTURE.md:24andARCHITECTURE.md:45. Keeping a second copy can drift; replace it with a pointer to those sections or move the agent-specific warning into the architecture owner.
- **Runtime Host is the only execution authority.** Desktop, TUI, CLI, and eval all execute through
it. A change that seems to need its own runtime is a design discussion, not an implementation
detail.
- **The Runtime Event Log is the source of truth**, and sessions, UI, model context, and recovery
are projections over it. Context pruning and compaction change what the next inference sees; they
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The first draft leaned so hard on "link, do not restate" that it stopped being usable on its own: no install step, no build command, no way to run the tests, and not one sentence saying what Maka is. An agent could read it end to end and still not be able to start. Restores the sections the format is for — project overview, repository layout, setup, development workflow, testing, code style, build and release, CI gates, PR conventions — while keeping references for the prose that other documents own. Commands belong here: they are the executable part, and CI catches them when they drift. Also corrects three things review caught. Generated artifacts are not only *.generated.ts; the ASF header rule has a reviewed exclusion list rather than covering every file; and not every workspace defines a test script. Adds the loading scope of workspace instructions, which is exactly cwd and ~/.maka with no ancestor walk — a session started in a subdirectory does not pick this file up at all. Generated-by: Claude Code Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Astro-Han
left a comment
Astro-Han
left a comment
There was a problem hiding this comment.
Reviewed at exact head fa72ed03bbf1bce0f563a78186fbc03fbf5b5cff.
Coverage: every factual claim the document makes about this repository, checked against the working tree at this head. Not covered: wording and style, and GitHub UI behaviour (for example how a PR title actually renders in a squash commit).
Result: no P0–P3 findings. Everything checked was accurate.
Spot-check of what was verified
- Node
engines >= 22.19.0, andci.ymlon node 24. Grepshells out torgviapackages/runtime/src/workspace-executor.ts:457.- The layout table's 10 workspaces plus
scripts/match the rootworkspacesfield. - The build order in the doc,
core → storage → mcp → runtime → runtime-host → computer-use → eval → cli → ui → desktop, matches the rootbuildscript exactly, includingcomputer-usebeforeeval. - Every script named in the doc exists:
dev,dev:full,rebuild,test:dist,test:dist:serial,lint,format,format:check,typecheck,check:asf-headers,check:release,check:asf-npm,check:asf-source,astryx:theme,astryx:surface-inventory:write,windows:inventory,release:cli:pack,smoke, and therelease:asf:source|verify|signtrio. - "Tests run from
dist/" matches each package'stest= clean + build +node --test dist/…;@maka/evalcorrectly has onlytest:distand chains the Python harbor suites. - Biome's dual role, the absence of any ESLint/Prettier config, and the single-quote / always-semicolon / 2-space / 100-column settings. The formatter excludes
apps/desktopandpackages/uiwhile still linting them, with the reason commented atbiome.jsonc:50;licenses/**andbundled-tools.jsonare excluded as byte-sensitive. - ASF header counts measured at this head: 2745 covered / 130 excluded, against the doc's "about 2,750 / about 130".
- Squash is the only merge method enabled on the repository.
- The CONTRIBUTING.md policy the doc paraphrases — AI review does not count, and the Generated-by trailer requirement — matches the source.
- "Maka reads it":
buildWorkspaceInstructionsPromptFragmentinjects it into the system prompt, andreadWorkspaceInstructionsreads only files directly under the given root, so the stated scope (session cwd plus~/.maka, no ancestor traversal) is correct.CLAUDE.mdis a symlink toAGENTS.md.
Why this is a comment and not an approval
Hosted checks have not run on this head — check-runs total_count is 0. Not-run is not green, so the CI gate is not cleared regardless of the review outcome. Happy to convert this to an approval once checks go terminal green.
M4n5ter
left a comment
M4n5ter
left a comment
There was a problem hiding this comment.
English
Independent COMMENT-only review at exact head fa72ed03bbf1bce0f563a78186fbc03fbf5b5cff.
Result: NO-GO while the P2 below remains. I found no other P0–P2 correctness or documentation-consistency findings. Hosted test is currently CANCELLED (run 32629944907), so there is no terminal-green CI evidence for this head. Local git diff --check and relative-link audit pass; the runtime package build could not start because this checkout lacks @types/node.
中文
在精确 head fa72ed03bbf1bce0f563a78186fbc03fbf5b5cff 上独立进行 COMMENT-only 审查。结论：P2 未解决前 NO-GO；未发现其他 P0–P2 正确性或文档一致性问题。Hosted test 当前为 CANCELLED（run 32629944907），因此没有该 head 的终态绿色 CI 证据。本地 diff-check 与相对链接审计通过；runtime 构建因 checkout 缺少 @types/node 未能启动。
Astro-Han
left a comment
Astro-Han
left a comment
There was a problem hiding this comment.
Independent review at exact head fa72ed03bbf1bce0f563a78186fbc03fbf5b5cff on one axis our earlier review did not test: this file is not only documentation, it is runtime input to the product in this repository. One [P1] inline — the document is more than twice the size Maka will inject, and the half that is dropped is the half that prevents mistakes. Details and three possible resolutions are on the inline comment at AGENTS.md:133, the line the truncation lands on.
This does not contradict review 5002101226: every factual claim that review checked is still accurate. It checked the file as prose; this checks it as an injected artifact.
| build: | ||
|
|
||
| ```sh | ||
| npm --workspace @maka/desktop run test # main-process unit tests |
There was a problem hiding this comment.
[P1] This file is 13,091 codepoints; Maka injects at most 6,000. 54% never reaches the agent, and the cut lands two characters into this line, inside an open ```sh fence.
Mechanism (packages/runtime/src/system-prompt/workspace-instructions.ts on main): MAX_WORKSPACE_INSTRUCTION_FILE_CHARS = 6000 at :42; truncateCodepoints at :143 slices at exactly 6,000 with no block or sentence awareness; injected for every run whose cwd is this repo (runtime-host/src/server/interactive-run-composer.ts:241).
Measured at this head: 13,091 codepoints, 7,091 dropped, 45.8% survives. Six of thirteen sections arrive; seven do not — Code style, Build, packaging and release, What CI enforces, Pull requests, Working method, Platform notes, About this file.
The dropped half is the half that prevents mistakes. The PR description's own example of knowledge "only recorded in code today" — Biome formatting the tree except apps/desktop and packages/ui — is in Code style, dropped. So is What CI enforces. An agent gets the layout and how to run tests, and nothing about the rules it is judged by.
The fragment also ends mid-command at ...build:\n\n```sh\nnp, leaving an unterminated fence. The prompt appends a generic [instructions truncated] (:84), so the model is not told it is holding a broken fence.
None of this is visible in git diff — it happens only at injection time.
Any one of these resolves it, no preference: bring the file under 6,000 and front-load Code style / What CI enforces / Pull requests; or split into a short root file plus a long guide in docs/; or raise the cap in its own PR first — but that changes behaviour for every Maka user's workspace, so it should be argued separately rather than arriving as a side effect.
One thing this PR gets right: the CLAUDE.md symlink does not double-inject. readWorkspaceInstructions digests cleaned text and skips repeats within a directory (:120-138), so identical bytes under two names collapse to one block — the behaviour #3578 (877dc962e) landed.
中文
[P1] 文件 13,091 码位，Maka 最多注入 6,000，54% 到不了 agent；切点在本行第 2 个字符，处在未闭合的 ```sh 围栏里。
上限见 workspace-instructions.ts:42，:143 按码位硬切、不认代码块边界；注入点 interactive-run-composer.ts:241，凡 cwd 为本仓的会话都注入。实测丢弃 7,091、存活 45.8%。13 节中 7 节到不了：Code style、Build/packaging/release、What CI enforces、Pull requests、Working method、Platform notes、About this file。
丢掉的正是能防错的那半：PR 描述举例的"Biome 排除 apps/desktop 和 packages/ui"就在 Code style 里。片段还以 ```sh\nnp 结尾，围栏未闭合，而提示词只追加通用的 [instructions truncated]。git diff 里看不到这些——只发生在注入时刻。
三种解法任选：压到 6,000 以下并前置 Code style / What CI enforces / Pull requests；或拆成"根目录短文件 + docs/ 长文"；或另开 PR 先抬高上限——但那改的是所有用户的工作区行为，应独立论证。
有一处做对了：CLAUDE.md 符号链接不会重复注入（:120-138 按内容摘要去重，#3578 落地）。
|
Please take this to a Discussion or Why: root
Four questions the Discussion should settle, because they determine the file's shape:
This branch is good raw material for that proposal — it already surfaces knowledge that exists only in code today. If the project agrees it wants a root 中文建议先走 Discussion 或 根目录 四个该在讨论里定的问题：要不要这个文件；它是事实地图还是规范性指令（草稿两者都有）；谁有修改权；尺寸预算多少（运行时上限 6000 码位，草稿超出一倍以上）。 这个分支是提案的好原材料，项目若同意要，大部分工作已完成。 |
Summary
Maka already reads
AGENTS.md—buildWorkspaceInstructionsPromptFragmentinjects it into the system prompt — but the repository has never had its own. An agent working here starts with nothing but the source tree.It covers what the AGENTS.md format is for: project overview, repository layout, setup, development workflow, testing, code style, build and release, the CI gate list, PR conventions, and a working method. Commands are written out rather than deferred to
package.json, because they are the executable part and CI catches them when they drift; prose that other documents own — contribution policy, architecture — stays a link.Some of it is only recorded in code today: that every workspace tests against compiled
dist/rather thansrc/, that Biome formats the tree exceptapps/desktopandpackages/uibecause desktop's source-contract tests regex-match exact source shapes, and that workspace instructions load from exactlycwdand~/.makawith no ancestor walk.CLAUDE.mdis a symlink to it. Each agent CLI reads one filename — Claude Code readsCLAUDE.md, Codex readsAGENTS.md, Gemini CLI readsGEMINI.md— so one canonical file plus a link avoids two copies that drift.apache/airflowdoes the same.Verification
npm run check:asf-headers,npm run lint,npm run format:checkall pass. Every path the file links to was checked to exist.The file is 13,091 characters, which is in the normal range for this format —
apache/kafkais 9.7 KB,apache/iceberg13 KB,apache/airflow35 KB.Known interaction
With the symlink present, Maka injects the same content twice — once as
AGENTS.md, once asCLAUDE.md— becausereadWorkspaceInstructionsreads every candidate name and never compares them:That is a pre-existing gap rather than something this PR introduces, and it is filed separately. Other agents avoid it either by reading a single filename (Claude Code, Codex, Gemini CLI), by first-match-wins (opencode, Pi), or by content-digest deduplication (DeepSeek Harness, which ships the same symlink). If reviewers would rather not land the symlink before that fix, dropping
CLAUDE.mdfrom this PR is a one-file change and the rest stands on its own.AI use
Select exactly one:
Tool(s) and scope: Claude Code — surveyed the repo and comparable projects, drafted the file, and verified each claim against the file it names.
Checklist
Does this PR entail a change in behavior?
No runtime source changes, but this file is prompt input for Maka sessions run in this repository, so adding it changes model behaviour here. Flagging it rather than treating the checkbox as docs-only.
Question for maintainers: the workspace-instruction size cap
MAX_WORKSPACE_INSTRUCTION_FILE_CHARSis 6000 andMAX_WORKSPACE_INSTRUCTIONS_PROMPT_CHARSis 14000, so Maka truncates this file at roughly 46% of its length and appends[instructions truncated]. Everything from "Build, packaging and release" onward is cut.An earlier revision of this PR was compressed to fit. That turned out to be the wrong trade: it removed the install step, the build command, how to run tests, and any statement of what Maka is — which is most of what the format exists to provide. Optimising a file whose audience is every agent against one consumer's cap degraded it for all of them.
The cap also looks low against comparable projects. Of the ASF repositories that ship an
AGENTS.md,apache/kafka(9.7 KB),opendal(8.5 KB),seatunnel(7.3 KB),pekko(7.3 KB),doris(12 KB),iceberg(13 KB),flink(23 KB),spark(20 KB),superset(16 KB),camel(33 KB) andairflow(35 KB) all exceed 6000 characters; onlypaimon,datafusionandgravitinofit under it. For comparison, Claude Code loads aCLAUDE.mdup to 4 MiB. The mandatory ASF licence header alone consumes 793 characters, 13% of the current per-file budget.Three options, and I do not have a strong view on which is right:
Happy to open a separate issue if this is worth pursuing; it is out of scope for this PR either way.